Welcome to Hsoi's App Shell! I hope you find this as much of a helpful tool in MacOS programming as I did in writing it.
What is Hsoi's App Shell?
Hsoi's App Shell, or "HAS" for short, is a collection of C code aimed at helping MacOS programmers learn how to do things. These things range from basic application functionality such as working with menus, to more advanced things such as dialog filters and handling AppleEvents to working with Text-To-Speech, the Drag Manager, how to use the TextEdit replacement engine WASTE, and much much more. For a longer list of what HAS can do, see the file "What HAS Can Do".
There are many many things that HAS offers to MacOS programmers in terms of code. Some of these things are very obvious (like how to use WASTE), some are more subtle (like how to properly save files using temporary files and checking for locked files). No matter how you use HAS -- as a teaching tool, as an example, as starting code, as a library, or whatever you choose to use HAS for, I hope it will be useful to you.
How do I use HAS?
Almost any way you like really. In and of itself, HAS doesn't do a lot...not like some game or demo. There is a "Hsoi's App Shell Demo" application that was made using HAS (and you are probably reading this document in that demo application). You can play with the demo to see the sorts of things HAS can show you, but playing with the demo will only show you so much; there is a lot more going on here than is obvious, so the best place to really utilize HAS is on the code level. See how something behaves in the demo. Find the related code files and functions for that application behavior. See what's going on. For example, look at the dialog filters (especially maybe the one for the Speech Options dialog box). See all the subtle things that go on.
Then, keep HAS around. Go through the code and see what's going on. Run the project with a debugger so you can step through line by line and watch what's happening. Then, get a good idea of what HAS demonstrates. Later in your programming efforts, if you get stuck on how to do something, refer back to HAS and see if there might be an example of how to do what you want to do. You could copy the HAS code and paste it into your project; modify it to suit your specific needs. Or maybe HAS doesn't show you exactly how to do what you want to do, but it might give you a place to start or to find an idea or break that "programmers block".
HAS can also be used as a code repository, a source of code for reuse. There are a lot of functions in HAS that you can just extract and plug into your own projects. Code reuse is a wonderful thing...why reinvent the wheel?
So, you think you know it all or something?
No, I don't know it all. I am not the greatest programmer in the world. I'm no Peter Lewis, I'm no Quinn, I'm no Eric Scouten, no Marco Piovanelli, (and the list can go on). But I just remember all the crud that I had to go through to learn MacOS programming, and I'm hoping that my efforts might help make future MacOS programmers a little less hellish.
Writing HAS was a big learning tool for me. I don't know if you'll be able to tell in the code, but I can look at some portions and see how green I was when I wrote it, and then look at some recently written code and see just how far I've come. I hope it can be a good learning tool for you too.
But since HAS was a learning tool for me, I know that HAS is not bug free, USE IT AT YOUR OWN RISK. I do strive for a good product, but I do not have the resources (nor the time) that big-time developers have. HAS has been tested and a lot of the code is known to be working and good, but it's not perfect, yet. For more information, see the "HAS TODO" file and the "HAS KNOWN BUGS".
What are the specifics to use HAS?
Well, that's two parts: hardware/software requirements, and legal information.
As for hardware and software, I used Metrowerks CodeWarrior to develop HAS. It is my platform of choice for development, and in my opinion, it's the development environment to use. So, you'll need at least the minimum system requirements for CW in order to use HAS (at least System 7.1, at least a 68020 processor or PowerPC processor). Things such as amount of RAM and hard drive space are up to you. The more the merrier, but HAS in and of itself doesn't require much of either.
To give you an idea, here's what I used to originally develop HAS:
Macintosh IIvx with 20 megs RAM, Daystar Turbo 040 Accellerator
System 7.1 w/ Drag Manager, Text-to-Speech Manager, AppleScript all installed
System 7.5.3 was also used for testing
Metrowerks CodeWarrior Academic 9 (all the latest versions via online updates)
Metrowerks Debug
Macsbug 6.5.3
ZoneRanger
EvenBetterBusError
DoubleTrouble
DisposeResource
ResEdit
a direct Internet link (not necessary, but has proven to be handy from time to time)
Then I bought a PowerMac 8500/150 48/2000. Ran MacOS 7.5.5, used CodeWarrior Gold 10, and life continues along.....and for this 1.0a3 release, I have MacOS 7.6, CW11, converted over to the Metrowerks Standard Library...NeXT and Apple are merging...life continues.
In addition to the code that I wrote, I also reused a lot of code and used some code libraries:
WASTE 1.3a3 by Marco Piovanelli
WASTE Object Handlers 1.2.4 by Michael Kamprath and me
Show_help by James Walker
Internet Config 1.3 by Peter Lewis and Quinn
code snippets from books by Scott Knaster, Keith Rollins, Dave Mark, Cartwright Reed, Gary Little, Tim Swihart
code snippets from John Norstad's NewsWatcher, from Apple DTS, from the new Inside Macintosh, from Tom Bender's Tex-Edit+ 1.6.3, from Marco Piovanelli's Movable Modal Library 2.0, from the WASTE Demo App by Marco Piovanelli and me, from Metrowerks sample code.
And I also had lots of help from people on the 'net.
The code in HAS does have some requirements.
• Requires at least System 7
• Assumes at least a 68020 processor (for Color QuickDraw. It might work on 68000 machines, but I'm not working for it)
• Things such as the Drag Manager, Speech Manager, AppleScript, etc. are not required for HAS to function, but they are nice to allow you to see and work with these great new bits of MacOS functionality. If you have at least System/MacOS 7.5.0, you will have all of these. If you have System 7.1, you can obtain the necessary extensions, if you have less than 7.1, you are probably out of luck.
As for the legal information, please refer to the "HAS Legal Info" document that should have been included with this distribution. If you do not have this document, please contact me for a copy. Lack of having and reading this document does not "exempt" you from the legal information.
How do I contact you?
Well, my only request in using HAS is to somehow register with me, mostly giving me some sort of idea as to who is using HAS and how I can get in touch with you if needed.
To then get in touch with me, I'd prefer if you did use email since I'm pretty much horrible about writing snail mail
email: <mailto:hsoi@eden.com>
And here's my main web page URL:
<http://www.eden.com/~hsoi/>
and I don't have a page dedicated to HAS, but I do have one for my programming projects in general:
<http://www.eden.com/~hsoi/prog.html>
Please give the rest of the HAS documentation a read over, look over the source, and give it a whirl! Please let me know what you think of it, and of course, if you find bugs or problems, find solutions/fixes for bugs and problems, have suggestions for future releases, impliment more functionality into HAS, do some of my "future" hopes for HAS, or whatever, please do contact me!
